The World of Computer Software

home *** CD-ROM | disk | FTP | other *** search

/ The World of Computer Software / The World of Computer Software.iso / triplt10.zip / TRIPLOT.DOC < prev next >

Wrap

Text File | 1992-07-13 | 27KB | 727 lines

================================================================= Version 1.00 TriPlot(tm) July 13, 1992 (C) Copyright 1992, Yves Beaudoin All Rights Reserved DOCUMENTATION ================================================================= TABLE OF CONTENTS ~~~~~~~~~~~~~~~~~ 1. OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. PREPARING A DATA FILE . . . . . . . . . . . . . . . . . . 3 2.1 Title . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 Output device code . . . . . . . . . . . . . . . . . 5 2.3 Output orientation . . . . . . . . . . . . . . . . . 5 2.4 Legend code . . . . . . . . . . . . . . . . . . . . 5 2.5 Corner code . . . . . . . . . . . . . . . . . . . . 6 2.6 Grid code . . . . . . . . . . . . . . . . . . . . . 6 2.7 Zonation code . . . . . . . . . . . . . . . . . . . 7 2.8 Normalization . . . . . . . . . . . . . . . . . . . 7 2.9 Bottom-edge label . . . . . . . . . . . . . . . . . 7 2.10 Left-edge label . . . . . . . . . . . . . . . . . . 7 2.11 Right-edge label . . . . . . . . . . . . . . . . . 7 2.12 Data records . . . . . . . . . . . . . . . . . . . 8 3. RUNNING TRIPLOT . . . . . . . . . . . . . . . . . . . . . 9 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- 1. OVERVIEW ~~~~~~~~~~~ TriPlot generates HP-GL/2 instructions for plotting three-component data on a ternary diagram. HP-GL/2 is the new standardized version of the Hewlett-Packard Graphics Language. It is available, for example, with HP's series of LaserJet III printers and DraftMaster plotters. The plot commands may be redirected to a file for processing at a later time. The user can specify a title and the labels for the edges of the diagram. A legend describing the number of data points plotted with a specified symbol and pen code can be optionally selected. The resolution of the grid system can be selected from five possibilities. Currently, there are two zonation schemes built into TriPlot, namely the soil textural zones defined by the Canadian Soil Survey Committee (1978) and those published by Shepard (1954). If you would like to see a particular well-established scheme made part of TriPlot, just forward to the author the values of the end points that make up the zone boundaries and a diagram of the scheme. The complete diagram can be plotted, or you can constrain the plot to an apex. Note in passing that all line segments such as zonation boundaries will be properly clipped for any corner plot. TriPlot can normalize the data to 1, 10, or 100. Normalized data points have their component values adjusted so that their sum is equal to 1, 10, or 100. Each data point can have a symbol and a color/pen associated with it. There are eight possible pen selections and eight possible symbols. There is a ninth symbol-code available for omitting the representation of a data point. This symbol-code must be used when designating the end point of a line segment. The total number of data points and line-segment end points must not exceed 1000. ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 2 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- Plot size is strictly dependent on the output media size. The same plot file can be directed to an HP LaserJet III with letter-size paper or to an HP DraftMaster SX+ with E-size paper mounted. The resulting diagram will be automatically adjusted to fit up to the hard-clip limits of the device, and, accordingly, be expanded or contracted. 2. PREPARING A DATA FILE ~~~~~~~~~~~~~~~~~~~~~~~~ An input data file for Program TriPlot must be a DOS text file conforming to a specific structure. There are two major sections to any data file. The first section consists of the plotting options and the labels for the ternary diagram. The second section groups the data components and their display codes. An example is provided by TEST.DAT, one of the many data files used to develop TriPlot. If you examine this file, you can see the two major sections. Moreover, you'll notice that each record has a row or column heading associated with it. Though not required, the headings help interpret the subsequent alphanumeric entries and, therefore, make the data file more understandable. To help you set up a data file, the distribution package includes the file TEMPLATE.DAT. As suggested by its name, the file is a data-entry template containing all the record field headings mentioned above. To illustrate its use, suppose that we want to set up a data file to be called MYDATA. The first step is to use the DOS COPY command to duplicate the contents of the template file to MYDATA. After making the TriPlot directory the current one, enter the following command: COPY TEMPLATE.DAT MYDATA /V where the /V switch instructs DOS to verify that MYDATA was written correctly. The next step is to load MYDATA into a text editor, such as the MS-DOS EDLIN or EDIT program, to enter the plotting parameters and your data. Note in passing that if you use a word processor instead, it should be configured to emulate a text processor. The left margin must correspond to Column 1 and the right one to Column 80 or more. The top and bottom ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 3 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- margins must be inactive. Headers and footers are not allowed. Finally select a monospace font, such as Courier, to ensure that your entries are aligned properly and remain so after you save them to disk. If the aforementioned operations have been carried out successfully, the file MYDATA consists of the following twelve lines: Title (30 chars. max): Output device code (0-1): Output orientation (-90,0,90): Legend code (0-1): Corner code (0-3): Grid code (0,10,20,40,50,100): Zonation code (0-2): Normalization code (1,10,100): Bottom-edge label (20 chars. max): Left-edge label (20 chars. max): Right-edge label (20 chars. max): Bottom---Left---Right---Symbol(0-8)---Pen(1-8)---Linkage Each line of the data file makes up a record. Information enclosed between parentheses represents the constraints or admissible values for a particular record or field. The first eleven records make up the first major section. The first record is for the title of the plot. Records #2 to #8 are for specifying the plotting options. Records #9 to #11 are dedicated to the labels of the diagram. For these records, input always begins at Column 35 immediately following the colon. The second major section begins with Record #12. This line is present solely for providing the column headings describing the subsequent data entry sequence. The component values and their display codes are entered in a tabular fashion, after Record #12. Descriptions and constraints for each record are as follows: 2.1 Title ~~~~~~~~~ The first record is for the title of the plot that will appear above the top apex of the diagram. There is a limit of thirty characters. ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 4 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- 2.2 Output device code ~~~~~~~~~~~~~~~~~~~~~~ The second record is for specifying the output-device type. The possible values and their corresponding meanings are: Code | Interpretation ------+-------------------------------------------- 0 | Plotter with a maximum capacity of 8 pens 1 | Monochrome printer such as a laser printer The purpose of this option is as follows. As explained in Section 2.12, the data points on the diagram can be distinguished by symbol and by colour when using a plotter. If you take advantage of this feature when you create your data file but then send the output to a laser printer, the colour distinction will be lost of course. With the output device code set to 1 on the other hand, Triplot will override all colour settings to black and adjust the legend accordingly by grouping the data points by their symbol codes only. It is faster to change this one record than to modify all the colour codes for the data points. 2.3 Output orientation ~~~~~~~~~~~~~~~~~~~~~~ The third record is for assigning an orientation to the plot. The following table defines the possible rotations: Code | Interpretation ------+-------------------------------- -90 | Rotate the plot by -90 degrees 0 | No rotation 90 | Rotate the plot by +90 degrees This option allows you to select a portrait or a landscape orientation to the output. 2.4 Legend code ~~~~~~~~~~~~~~~ The fourth record is for toggling the legend. The associated code is defined as follows: Code | Interpretation ------+----------------- 0 | No legend 1 | Draw the legend ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 5 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- The legend is drawn to the left of the ternary diagram and consists of the following features: o the name and version number of the program, o the date and time the plot was created, o a listing of the coloured symbols used along with a frequency count of the corresponding data points, o a listing of the pens mounted in the carousel if the output device code is set to 0. Finally a frame is drawn which encloses the legend and the diagram. 2.5 Corner code ~~~~~~~~~~~~~~~ Record #5 is for the corner code defined as: Code | Interpretation ------+----------------------------------- 0 | Plot the whole diagram 1 | Plot the bottom left corner only 2 | Plot the top corner only 3 | Plot the bottom right corner only Note in passing that when zooming in to a corner of the diagram, all zonation boundaries, tie lines, and line segments will be clipped accordingly. 2.6 Grid code ~~~~~~~~~~~~~ The next record is for choosing a predefined grid system. Admissible values and their actions are: Code | Interpretation ------+--------------------------------------------- 0 | No grid 10 | Very coarse grid (10 subintervals per edge) 20 | Coarse grid (20 subintervals per edge) 40 | Medium grid (40 subintervals per edge) 50 | Fine grid (50 subintervals per edge) 100 | Very fine grid (100 subintervals per edge) The corresponding annotation is controlled by TriPlot. Regardless of the value of the grid code, there will always be nine annotation labels per edge. ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 6 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- 2.7 Zonation code ~~~~~~~~~~~~~~~~~ The seventh record is for specifying which zonation scheme to superimpose onto the plot: Code | Interpretation ------+----------------------------------------------- 0 | No zonation 1 | Soil textural zones defined by the Canadian | Soil Survey Committee (1978) 2 | Soil textural zones defined by Shepard (1954) If you use other well-established zonation schemes, send us the details and they will be incorporated into the next version. 2.8 Normalization ~~~~~~~~~~~~~~~~~ Record #8 allows you to indicate how the component data is to be normalized: Code | Interpretation ------+----------------------------------- 1 | Set the data component sum to 1 10 | Set the data component sum to 10 100 | Set the data component sum to 100 2.9 Bottom-edge label ~~~~~~~~~~~~~~~~~~~~~ Record #9 is the label for the bottom edge of the triangular diagram: there is a maximum of twenty characters allowable. 2.10 Left-edge label ~~~~~~~~~~~~~~~~~~~~ Record #10 is the label for the left edge of the triangular diagram: there is a maximum of twenty characters permitted. 2.11 Right-edge label ~~~~~~~~~~~~~~~~~~~~~ Record #11 is the label for the right edge of the triangular diagram: there is a maximum of twenty characters allowable. ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 7 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- 2.12 Data records ~~~~~~~~~~~~~~~~~ Record #12 consists of column headings for the remaining data records: it is provided solely to facilitate subsequent data entry. Record #13 is associated with the first data point. It is made up of six numeric fields that correspond to the six headings of Record #12. The first three fields are the coordinate components corresponding to the bottom edge, the left edge, and the right edge of the diagram in that order. The remaining fields are for the symbol, pen, and linkage codes. All field entries are separated from each other by blank spaces. The various symbol codes will result in the following representations of the data points: Code | Representation ------+---------------------------------------- 0 | No symbol: used in conjunction with | the linkage code to draw line segments 1 | Circle 2 | Square 3 | Triangle 4 | Diamond 5 | Dot, i.e. filled circle 6 | Filled square 7 | Filled triangle 8 | Filled diamond The integer pen codes designate the pen stall from which the pen will be selected. For a plotter, the limit is normally eight. Thus, TriPlot conforms to this maximum value. On a monochrome output device, only "Pen #1" is available. However, remember that TriPlot will automatically override a pen code greater than 1 if the output device code has been set to 1. Note that "Pen #1" is always used to draw the grid system and the annotation. The last record field is for an integer value (in the range -32768 to 32767) describing the linkage code. Its purpose is to allow tie lines and/or line segments to be included in the plot. A linkage code value equal to zero isolates the data point. Any two consecutive data points with the same non-zero linkage code value are deemed to be linked by a tie line. Moreover if the symbol codes are zero, the result will be a line segment. ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 8 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- Therefore, the following entries in a data file Bottom---Left---Right---Symbol(0-8)---Pen(1-8)---Linkage 30. 30. 40. 1 4 1 34. 25. 41. 3 4 1 will result in a tie line, that is, a line segment between the circle symbol of the first point and the triangular representation of the second point. On the other hand, the entries Bottom---Left---Right---Symbol(0-8)---Pen(1-8)---Linkage 30. 30. 40. 0 4 1 34. 25. 41. 0 4 1 will only produce a line segment. Accordingly, you can incorporate any zonation scheme into the ternary diagram. But, as remarked previously, the author will update TriPlot with any well-established zonation scheme provided that a complete description is sent. Record #14 and subsequent records are for the remaining data points, each structured as explained previously. Note in passing that you can delimit groups of data records using blank lines: these extra lines will be ignored by TriPlot. Once you have specified all the plotting options and entered your data, save the information back to disk overwriting the original file, e.g., MYDATA. If you are using a word processor, insure that the file is saved as a DOS text file. You are now ready to process your data file. 3. RUNNING TRIPLOT ~~~~~~~~~~~~~~~~~~ There are two ways of starting the execution of Program TriPlot, depending on where the output results are to be directed. At the DOS command line, you can enter either TriPlot DataFileName OutputFileName or TriPlot DataFileName OutputDevicePort ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 9 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- where, DataFileName is the name of the data file, OutputFileName is the name of the file to which the results will be written, OutputDevicePort is the name of the device port to which the results will be sent, e.g., COM1 for a plotter connected to the first serial port. If required, use the DOS MODE command beforehand to configure the port. Note that file names may be prefixed with a path specification. The following names are reserved for the operating system devices: Name | Device ------+------------------------------- AUX | Communications port (COM1) COM1 | Communications port CON | Keyboard and screen ERR | Standard error output (screen) LINE | Communications port (COM1) LPT1 | Printer NUL | Null device PRN | Printer (LPT1) USER | Keyboard and screen The connection is always to the device, even if a disk file with the same name already exists, regardless of its extension. Consult your DOS manual for more information if these port designations are unfamiliar. As an example of the output file name usage, the command TRIPLOT TEST.DAT B:TEST.PLT instructs TriPlot to retrieve the data file TEST.DAT on the current logged-on drive and to store the resulting HP-GL/2 commands into the file TEST.PLT on Drive B:. If TEST.PLT exists beforehand, TriPlot would seek your permission to overwrite with the new output results. On the other hand, to process the data file MYDATA and to direct the results to a laser printer connected through the first parallel port, the following command would be issued: ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 10 TriPlot(tm) Documentation Version 1.00 ----------------------------------------------------------------- TRIPLOT MYDATA LPT1 If your HP laser printer should generate a "21 PRINT OVERRUN" error message, you'll have to set the "Page Protection" feature (see the printer's user manual for more details). Once page composition is finished, you must issue a form-feed command. As TriPlot sequently reads and processes the data file, the various options will be echoed to the screen. Wherever applicable, short interpretations will also be included. Many error traps have been built into TriPlot to detect erroneous entries in the data file or problems with disk-related operations. Corresponding messages will be printed to the screen. TriPlot will continuously update the total number of data records successfully read. Thus the location of an incorrect record can be inferred readily. During debugging, you can direct the output to NUL, the black-hole of DOS device- drivers, to suppress plotting or to CON to see the resulting HP- GL/2 commands. If everything goes smoothly, you'll see the message "Done!" appear as the last line on the screen. ----------------------------------------------------------------- (C) Copyright 1992, Yves Beaudoin 11